From: Robert Pluim Date: Mon, 28 Jul 2025 12:11:50 +0000 (+0200) Subject: Prefer "tls" to "ssl" in documentation X-Git-Tag: archive/raspbian/1%30.2+1-2+rpi1^2~2^2~24^2~16 X-Git-Url: https://dgit.raspbian.org/%22http:/www.example.com/cgi/%22https://%22Program/%22http:/www.example.com/cgi/%22https:/%22Program?a=commitdiff_plain;h=57a9798c22a6d8a75883dfcc1c4430be428d20bb;p=emacs.git Prefer "tls" to "ssl" in documentation * doc/misc/gnus.texi (NNTP): Refer to 'nntp-open-tls-stream'. (Direct Functions, Customizing the IMAP Connection): Add commentary about desirability of STARTTLS. Correct documentation about use of GnuTLS. Use 'tls in example. * lisp/gnus/nnimap.el (nnimap-server-port): Mention 'tls in preference to 'ssl. * lisp/gnus/nntp.el (nntp-open-connection-function) (nntp-never-echoes-commands): Document 'nntp-open-tls-stream' as preferred to 'nntp-open-ssl-stream'. --- diff --git a/doc/misc/gnus.texi b/doc/misc/gnus.texi index 13b4a339987..662f2f21301 100644 --- a/doc/misc/gnus.texi +++ b/doc/misc/gnus.texi @@ -14089,7 +14089,7 @@ indirect ones (three pre-made). Non-@code{nil} means the nntp server never echoes commands. It is reported that some nntps server doesn't echo commands. So, you may want to set this to non-@code{nil} in the method for such a server setting -@code{nntp-open-connection-function} to @code{nntp-open-ssl-stream} for +@code{nntp-open-connection-function} to @code{nntp-open-tls-stream} for example. The default value is @code{nil}. Note that the @code{nntp-open-connection-functions-never-echo-commands} variable overrides the @code{nil} value of this variable. @@ -14145,18 +14145,26 @@ functions is also affected by commonly understood variables @findex nntp-open-network-stream @item nntp-open-network-stream This is the default, and simply connects to some port or other on the -remote system. If both Emacs and the server supports it, the -connection will be upgraded to an encrypted @acronym{STARTTLS} -connection automatically. - -@item network-only -The same as the above, but don't do automatic @acronym{STARTTLS} upgrades. +remote system. If both Emacs and the server supports it, the connection +will be upgraded to an encrypted @acronym{STARTTLS} connection +automatically. If you want to avoid the possibility of a malicious +intermediary blocking the use of @acronym{STARTTLS}, use +@code{nntp-open-tls-stream} instead. + +@item nntp-open-plain-stream +@itemx network-only +The same as the above, but don't do automatic @acronym{STARTTLS} +upgrades. Only use this if you want anyone to be able to read your +traffic. @findex nntp-open-tls-stream @item nntp-open-tls-stream Opens a connection to a server over a @dfn{secure} channel. To use -this you must have @uref{https://www.gnu.org/software/gnutls/, GnuTLS} -installed. You then define a server as follows: +this, your Emacs must have been compiled with GnuTLS support +@uref{https://www.gnu.org/software/gnutls/, GnuTLS}. You can check this +using the @code{gnutls-available-p} command. + +You then define a server as follows: @lisp ;; @r{"nntps" is port 563 and is predefined in our @file{/etc/services}} @@ -14168,26 +14176,10 @@ installed. You then define a server as follows: (nntp-address "snews.bar.com")) @end lisp -@c FIXME openssl s_client should be deprecated in favor of gnutls. @findex nntp-open-ssl-stream @item nntp-open-ssl-stream -Opens a connection to a server over a @dfn{secure} channel. To use -this you must have @uref{https://www.openssl.org/, OpenSSL} -@ignore -@c Defunct URL, ancient package, so don't mention it. -or @uref{ftp://ftp.psy.uq.oz.au/pub/Crypto/SSL, SSLeay} -@end ignore -installed. You then define a server as follows: - -@lisp -;; @r{"snews" is port 563 and is predefined in our @file{/etc/services}} -;; @r{however, @samp{openssl s_client -port} doesn't like named ports.} -;; -(nntp "snews.bar.com" - (nntp-open-connection-function nntp-open-ssl-stream) - (nntp-port-number 563) - (nntp-address "snews.bar.com")) -@end lisp +This is the old name for @code{nntp-open-tls-stream}, and is +completely equivalent. @findex nntp-open-netcat-stream @item nntp-open-netcat-stream @@ -14529,7 +14521,7 @@ Here's an example method that's more complex: (nnimap-inbox "INBOX") (nnimap-split-methods default) (nnimap-expunge t) - (nnimap-stream ssl)) + (nnimap-stream tls)) @end example @table @code @@ -14555,11 +14547,12 @@ How @code{nnimap} should connect to the server. Possible values are: @table @code @item undecided -This is the default, and this first tries the @code{ssl} setting, and +This is the default, and this first tries the @code{tls} setting, and then tries the @code{network} setting. -@item ssl -This uses standard @acronym{TLS}/@acronym{SSL} connections. +@item tls +This uses standard @acronym{TLS}/@acronym{SSL} connections. @code{ssl} +is an equivalent but deprecated way to specify this. @item network Non-encrypted and unsafe straight socket connection, but will upgrade diff --git a/lisp/gnus/nnimap.el b/lisp/gnus/nnimap.el index 215e8ac4cbf..f813d513180 100644 --- a/lisp/gnus/nnimap.el +++ b/lisp/gnus/nnimap.el @@ -51,7 +51,7 @@ (defvoo nnimap-server-port nil "The IMAP port used. -If `nnimap-stream' is `ssl', this will default to `imaps'. If not, +If `nnimap-stream' is `tls', this will default to `imaps'. If not, it will default to `imap'.") (defvoo nnimap-use-namespaces nil @@ -63,10 +63,10 @@ names of your nnimap groups.") (defvoo nnimap-stream 'undecided "How nnimap talks to the IMAP server. -The value should be either `undecided', `ssl' or `tls', +The value should be either `undecided', `tls' or `ssl' (deprecated), `network', `starttls', `plain', or `shell'. -If the value is `undecided', nnimap tries `ssl' first, then falls +If the value is `undecided', nnimap tries `tls' first, then falls back on `network'.") (defvoo nnimap-shell-program (if (boundp 'imap-shell-program) diff --git a/lisp/gnus/nntp.el b/lisp/gnus/nntp.el index a086421b049..0d0a0e679fa 100644 --- a/lisp/gnus/nntp.el +++ b/lisp/gnus/nntp.el @@ -82,8 +82,9 @@ as its single argument, or one of the following special values: upgrading to a TLS connection via STARTTLS if possible. - `nntp-open-plain-stream' specifies an unencrypted network connection (no STARTTLS upgrade is attempted). -- `nntp-open-ssl-stream' or `nntp-open-tls-stream' specify a TLS - network connection. +- `nntp-open-tls-stream' specifies a TLS network connection (the + equivalent value `nntp-open-ssl-stream' is accepted for backwards + compatibility). Apart from the above special values, valid functions are as follows; please refer to their respective doc string for more @@ -100,7 +101,7 @@ For indirect connections: "Non-nil means the nntp server never echoes commands. It is reported that some nntps server doesn't echo commands. So, you may want to set this to non-nil in the method for such a server setting -`nntp-open-connection-function' to `nntp-open-ssl-stream' for example. +`nntp-open-connection-function' to `nntp-open-tls-stream' for example. Note that the `nntp-open-connection-functions-never-echo-commands' variable overrides the nil value of this variable.")